home *** CD-ROM | disk | FTP | other *** search
/ Windows 95 Super Collection / Windows 95 Super Collection.iso / win95 / network / netuser / call32.txt < prev    next >
Encoding:
Text File  |  1994-02-18  |  6.5 KB  |  167 lines
  1. CALL32.DLL: 32-bit DLL calling library for Visual Basic
  2. by Peter Golde
  3.  
  4. This program is placed in the public domain.
  5. Please feel free to redistribute as you wish.  
  6. No guarantees are made as to its suitability or
  7. usefulness, and no support can be provided.
  8.  
  9. 1. Summary
  10. ----------
  11.  
  12. CALL32.DLL is a DLL that can be used for calling routines in 32-bit
  13. DLLs on Windows NT.  It cannot be used on Windows 3.1, Win32s, Chicago,
  14. or other operating systems.  Using it, a Visual Basic program, running
  15. in the Win16 subsystem, can declare and call functions in any 32-bit
  16. DLL (including, but not limited to, the system DLLs).  CALL32.DLL works
  17. on both the x86 and MIPS versions on NT.  It has not been tested
  18. on Alpha or other versions, but should work.
  19.  
  20.  
  21. 2. Usage
  22. --------
  23.  
  24. To call a function in a 32-bit DLL, follow the following steps.  Declare
  25. the "Declare32" function as follows (all one one line):
  26.  
  27. Declare Function Declare32 Lib "call32.dll" (ByVal Func$,
  28.        ByVal Library$, ByVal Args$) As Long
  29.  
  30. Next, declare the function you wish to call.  Declare it in the ordinary 
  31. fashion, with the following exceptions:
  32.    - Use a library name of "call32.dll"
  33.    - Use an Alias of "Call32"
  34.    - Add an additional argument at the end, of type ByVal Long
  35. For example, if you are calling the function:
  36.   GetWindowText(HWND hwnd, LPSTR lpsz, int cch)
  37. declare it as follows (remember that ints and all handles are 32 bits,
  38. so use a Long):
  39.   Declare Function GetWindowText Lib "call32.dll" Alias "Call32"
  40.         (ByVal hwnd As Long, ByVal lpsz As String, 
  41.          ByVal cch As Long, ByVal id As Long) As Long
  42.  
  43. In the initialization section of your application, you declare the
  44. actual library and name of the function you want to call with 
  45. the Declare32 function.  Pass it the name of the function, the
  46. library, and a string describing the argument types.  Each letter
  47. in the string declares the type of one argument, and should be
  48. either "i" for a 32 bit integer or handle type, "p" for any
  49. pointer type, or "w" for an HWND parameter you want to pass
  50. a 16 bit HWND to and have be automatically converted to a 32 bit
  51. HWND.  The return value of Declare32 should be saved away in 
  52. a global variable to be passed as the last parameter to the
  53. function you declared earlier.  So, continue the example, you
  54. would call:
  55.  
  56.   idGetWindowText = Declare32("GetWindowText", "user32", "wpi")
  57.   
  58. (As a side note, this would be more properly declared as 
  59. "GetWindowTextA", since this is the real exported name.  However,
  60. Declare32 will automatically add an "A" to the end of a 
  61. function name if necessary).
  62.  
  63. To call the function, you would just call:
  64.  
  65.   cbCopy = GetWindowText(hwnd, sz, cb, idGetWindowText)   
  66.    
  67.    
  68. 3. Data Types and Handles 
  69. -------------------------
  70.  
  71. It is important to use the correct data types when calling DLL
  72. functions.  There are two important points to pay attention
  73. to when using CALL32.DLL.  First, only 32 bit integers can
  74. be passed to a DLL procedures.  Since virtually all 32 bit
  75. functions take int, UINT, LONG, DWORD, or HANDLE parameters,
  76. which are all 32 bits, this is not a major restriction.  However,
  77. you must remember to always declare functions arguments are
  78. Long, and not Integer.
  79.  
  80. Secondly, 16 bit handles and 32 bit handles are not interchangable.
  81. For example, a 16 bit bitmap handle that you get from calling
  82. a 16 bit DLL or from the VB environment cannot be passed to
  83. a 32 bit function expecting a bitmap handle.  Similarly, a 
  84. 32 bit handle gotten from a 32 bit function cannot be passed to a 
  85. 16 bit DLL.  The only exception is window handles (HWND).  If
  86. you declare a function parameter with the "w" letter in the 
  87. argument description string passed to Declare32, the corresponding
  88. parameter will be automatically converted from a 16 bit HWND to
  89. a 32 bit HWND when the call is made.  You must still declare the
  90. argument as a LONG.  This is convenient, for example, when passing
  91. the value returned by the "hWnd" property of a control to a 
  92. 32 bit DLL function.  Only windows created by your application
  93. can be translated.
  94.  
  95. Summary of data types:
  96.  
  97. C data type      Type specified in Declare   Character for Declare32
  98.  
  99. int, UINT          ByVal Long                  i
  100. LONG, DWORD        ByVal Long                  i
  101. HANDLE             ByVal Long                  i
  102. WORD, short        not supported                 
  103. HWND               ByVal Long                  w (i for no 16->32
  104.                                                   translation)
  105. LPSTR              ByVal String                p
  106. LPLONG, LPDWORD,
  107. LPUINT, int FAR *  Long                        p
  108. LPWORD             Integer                     p
  109.  
  110.  
  111. 4. Note on Declare32 function names
  112. -----------------------------------
  113.  
  114. Declare32 will automatically try three different names for
  115. the function name you pass in.  First, it uses the exact
  116. name you pass in.  If that function name isn't found,
  117. it converts the name to the stdcall decorated name convention,
  118. by adding an underscore at the beginning, and adding "@nn" at
  119. the end, where "nn" is the number of bytes of arguments.  If
  120. that name isn't found, it adds an "A" to the end of the original
  121. name to try the Win32 ANSI function calling convention.
  122.  
  123.  
  124. 5. Run-time Error Summary
  125. -------------------------
  126.  
  127. The following run-time errors can be generated by CALL32.DLL
  128.  
  129. 30001   Can't load DLL: "|" (error=|)
  130.    The DLL name passed to Declare32 was not the name of a 
  131.    valid 32 bit DLL. The Win32 error code is specified at the
  132.    end of the error message, this can help determine why
  133.    the DLL didn't load.  
  134.    
  135. 30002   Can't find specified function
  136.    The function name passed to Declare32 could not be found
  137.    in the DLL.
  138.    
  139. 30003   Invalid parameter definition string
  140.    The parameter definition string passed to Declare32 had
  141.    an invalid character in it, or was too long (32 parameters
  142.    is the limit).
  143.    
  144. 30004   Not running on Windows NT
  145.    The program is not running in the Windows16 subsystem of
  146.    Windows NT.
  147.    
  148. 30005   Invalid window handle
  149.    The 16 bit window handle passed as a parameter declared
  150.    with the 'w' character was not a valid 16 bit window handle,
  151.    or refers to a window from a different process.  
  152.  
  153.  
  154. 6.  Change History
  155. ------------------
  156.  
  157. 1.00       Original Version
  158. (8/31/93)    
  159.  
  160. 1.01       Better error message when DLL can't be loaded
  161. (9/27/93)  Stdcall name decoration support
  162.            Source code available
  163.            Sample Bezier program from Adam Rauch
  164.     
  165.    
  166.    
  167.